<h2>DESCRIPTION</h2>

<em>r.relief</em> creates a raster shaded relief map based on current
resolution settings and on sun altitude, azimuth, and z-exaggeration
values entered by the user.

<p>The parameters controlling the shading are:
<ol>
<li>An <b>input</b> raster map to provide elevation values for the shaded 
relief map. Typically, this would be a map layer of elevation; 
however, any raster map layer can be named.

<li>The <b>altitude</b> of the sun in degrees above the horizon
(a value between 0 and 90 degrees).

<li>The <b>azimuth</b> of the sun in degrees to the east of north (a
value between 0 and 360 degrees; clockwise from north)

<li>The scaling parameter, which compensates for a different 
horizontal <b>scale</b> than vertical scale. If <b>scale</b> is a 
number, then the ewres and nsres are multiplied by that scale to 
calculate the shading. (Default=1.0 for equivalent horizontal and 
vertical scales.)

<li>The <b>zscale</b> exaggeration factor that changes the apparent relief
for the shaded relief map. This can be any positive (or negative) floating
point value. (Default=1.0)

<li>Horizontal distances are calculated in meters, using geodesic 
distances for a latitude-longitude projection. With an elevation map 
measured in feet, the <b>units</b> option can be set to automatically 
convert meters to international feet (0.3048 meters = 1 foot) or survey 
feet (1200 / 3937 meters = 1 foot). The <b>units</b> parameter overrides 
the <b>scale</b> parameter.

</ol>

<p><em>r.relief</em> assigns a grey-scale color table to the new 
shaded relief map.

<h2>NOTES</h2>

To visually improve the result of shade maps from low resolution
elevation models,
use <em><a href="r.resamp.interp.html">r.resamp.interp</a></em> with
bilinear or bicubic method to resample the DEM at higher
resolution. <em>r.relief</em> is then run on the resampled DEM.

<p>
The current mask is ignored.

<h2>EXAMPLES</h2>

<h3>Shaded relief map</h3>

In this example, the aspect map in the North Carolina sample
dataset location is used to hillshade the elevation map:

<div class="code"><pre>
g.region raster=elevation -p
r.relief input=elevation output=elevation_shade
</pre></div>

<center>
<img src="r_relief.png" alt="GRASS r.relief result (subset)" border=0>
<br>
<i>r.relief: shaded elevation map (subset)</i>
</center>

<h3>Colorizing a shaded relief map</h3>

Color can be added later
using <em><a href="r.shade.html">r.shade</a></em>
or <em><a href="d.shade.html">d.shade</a></em>:

<div class="code"><pre>
r.shade shade=elevation_shade color=elevation output=elevation_shaded
</pre></div>

<h3>Using the scale factor in Latitude-Longitude</h3>

In Latitude-Longitude locations (or other non-metric locations), the
<em>scale</em> factor has to be used:

<div class="code"><pre>
# Latitude-Longitude example
g.region raster=srtm -p
r.relief input=srtm output=srtm_shaded scale=111120
</pre></div>

<h3>Exporting shaded relief maps to GeoTIFF</h3>

The data range of shaded relief maps usually does not permit exporting the
map to GeoTIFF format along with its associated color table due to limitations
in the GeoTIFF format.
<p>
The most simple way to export it while even reducing the file size is
to export as palette byte map. This requires a conversion done
in <em><a href="r.mapcalc.html">r.mapcalc</a></em>, using the #
operator to convert map category values to their grey scale
equivalents:

<div class="code"><pre>
# using the map created above

# create new map from map category values
r.mapcalc expression="elevation_shade_byte = #elevation_shade"

# verify data range
r.info elevation_shade_byte

# assign grey color table
r.colors elevation_shade_byte color=grey

# export (optionally: createopt="COMPRESS=DEFLATE,BIGTIFF=YES")
r.out.gdal input=elevation_shade_byte createopt="COMPRESS=DEFLATE" \
           output=elevation_shade.tif

# add overview images in GeoTIFF file for faster zooming
gdaladdo --config GDAL_CACHEMAX 2000 elevation_shade.tif 2 4 8 16
</pre></div>


<h2>SEE ALSO</h2>

<p>
<em>
<a href="d.shade.html">d.shade</a>,
<a href="d.his.html">d.his</a>,
<a href="g.region.html">g.region</a>,
<a href="r.shade.html">r.shade</a>,
<a href="r.blend.html">r.blend</a>,
<a href="r.colors.html">r.colors</a>,
<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.resamp.interp.html">r.resamp.interp</a>
</em>

<h2>AUTHORS</h2>

Jim Westervelt, U.S. Army Construction Engineering Research Laboratory
<br>
Markus Metz: Enhanced fast C version of r.relief for GRASS GIS 7

<!--
<p>
<i>Last changed: $Date$</i>
-->
